## 📘 API 接口文档

本系统提供标准 RESTful API 接口，用户通过 AppID 和 AppKey 进行鉴权。

### 通用说明

请求方式：POST（推荐）或 GET

统一入口：`/api/{接口名称}`

返回格式：JSON

鉴权方式：AppID + 签名验证

### 签名算法

1. 将请求参数按 key 排序（排除 sign 参数）

2. 拼接为 `key1=value1&key2=value2&app_key=YOUR_APP_KEY`

3. 对上述字符串计算 MD5，即为签名 sign

    function sign($params, $appKey) {
        ksort($params);
        $str = '';
        foreach ($params as $k => $v) {
            if ($k !== 'sign' && $v !== '') $str .= $k . '=' . $v . '&';
        }
        $str .= 'app_key=' . $appKey;
        return md5($str);
    }

### 接口列表

POST `/api/balance` - 查询余额/剩余次数

必填参数：app_id, timestamp, sign

    {"code":0,"msg":"ok","data":{"remain_calls":85,"expire_time":"2025-01-15"}}

POST `/api/idcard` - 身份证二要素核验

必填参数：app_id, name, idcard, timestamp, sign

    {"code":0,"msg":"ok","data":{"result":"一致","name":"张三","idcard":"110101****1234"}}

POST `/api/face` - 人脸识别比对

必填参数：app_id, image_base64, name, idcard, timestamp, sign

POST `/api/phone` - 运营商三要素核验

必填参数：app_id, name, idcard, phone, timestamp, sign

### 错误码

错误码 | 说明
--- | ---
0 | 成功
401 | 签名验证失败
402 | AppID不存在或应用已禁用
403 | 次数不足
404 | 套餐已过期
500 | 系统内部错误

## 📦 SDK 下载

建议在您的后端集成SDK以保证AppKey安全。

下载 PHP SDK 下载 Python SDK

### PHP 使用示例

    require 'auth_sdk.php';
    $sdk = new AuthSDK('https://your-domain.com', 'YOUR_APP_ID', 'YOUR_APP_KEY');
    $result = $sdk->getBalance();
    $result = $sdk->idcardVerify('张三', '110101199001011234');
    print_r($result);